Skip to content

feat(consolidation): Liquid UTXO consolidation with decoy outputs - #2494

Draft
wired-pasteque wants to merge 13 commits into
developfrom
consolidate-decoy-change
Draft

feat(consolidation): Liquid UTXO consolidation with decoy outputs#2494
wired-pasteque wants to merge 13 commits into
developfrom
consolidate-decoy-change

Conversation

@wired-pasteque

@wired-pasteque wired-pasteque commented Jul 21, 2026

Copy link
Copy Markdown
Collaborator

What

Adds Liquid wallet UTXO consolidation: when a wallet accumulates too many
confirmed L-BTC UTXOs, it's offered (via a banner on wallet/send/swap
screens) a guided flow to sweep them into fewer outputs, keeping the wallet
well under the ~256-input confidential-transaction limit before it ever
blocks a real send or swap.

The decoy output, and why it's there

A naive consolidation transaction is an obvious on-chain signature: many
inputs, one output, no counterparty — a many-in/one-out self-transfer. On a
transparent chain that's a privacy leak (heuristics like this are a
well-known way to cluster a wallet's UTXOs together). On Liquid, amounts and
assets are already blinded by confidential transactions, but the shape of
the transaction (input/output count) is still visible.

Each consolidation batch is built with two outputs instead of one: the
real drained amount, plus a second, small "decoy" output back to a
fresh address of the wallet's own. This makes the transaction look like an
ordinary two-output payment rather than a textbook consolidation. Because
Liquid hides amounts, the decoy value itself is never visible to
anyone but the wallet — only the shape of the tx (2 outputs, not 1) is
public, and that shape is indistinguishable from a normal payment.

The decoy UTXO is then frozen (best-effort) so it's never accidentally
swept back into a future consolidation round.

Also included

  • Frozen-UTXO enforcement in real sends/swaps — Liquid sends and
    auto-swap executions now explicitly exclude frozen UTXOs (previously only
    the UI bookkeeping did), so a frozen decoy or user-frozen coin can never
    be accidentally spent by a normal transaction.
  • Address-reservation datasource — prevents two addresses (e.g. two
    consolidation batches, or a batch running close to another
    address-generating event) from ever being handed out with the same
    index, closing a real address-reuse bug found during testing.
  • Sync gap-limit fix — a multi-batch consolidation round now syncs the
    wallet against the actual highest reserved address index afterward,
    closing a real "balance disappeared" bug where funded addresses could
    land outside the default 20-address gap-limit scan.
  • buildCustomTx — a new explicit-UTXO-list Liquid transaction builder
    (vs. the old coin-selecting builder), needed so consolidation, frozen-UTXO
    exclusion, and the decoy output can all specify exact inputs/outputs.

Testing

Tested using small amounts of UTXOs.

Screen.Recording.2026-07-21.at.6.46.27.PM.mov

@wired-pasteque wired-pasteque self-assigned this Jul 21, 2026
@wired-pasteque
wired-pasteque force-pushed the consolidate-decoy-change branch 2 times, most recently from 8918ec0 to 34d9ab4 Compare July 22, 2026 02:08
@wired-pasteque wired-pasteque changed the title tmp feat(consolidation): Liquid UTXO consolidation with decoy outputs Jul 22, 2026
@wired-pasteque
wired-pasteque requested a review from i5hi July 22, 2026 11:45
@wired-pasteque
wired-pasteque marked this pull request as ready for review July 22, 2026 11:45
@wired-pasteque
wired-pasteque marked this pull request as draft July 27, 2026 16:46
@wired-pasteque
wired-pasteque force-pushed the consolidate-decoy-change branch from 34d9ab4 to 0457121 Compare July 27, 2026 19:16
@ethicnology

Copy link
Copy Markdown
Member

@wired-pasteque can you rebase this branch?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants